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Fast 
o Otherwise you can use much more advanced alternatives like node.js. 
e Integrate well with asynchronous nature of NGINX 
e Modular 
e So people who do not need it, can disable it to squeeze out performance. 
e Popular scripting language 
o To help people to write their scripts faster. 
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Perl scripting 


e Existing perl libraries can be 7 No support for non-blocking 


used. IO. 
e Perl code can be embedded «Perl interpreter can exit the 
into nginx conf file. worker process. 
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Why JavaScript? 


e Modern lingua-franca 
o So, people can quickly understand it. 
e C-like syntax 
e Good match for nginx config files. 
e Event-driven paradigm is natural for JavaScript. 
e Good match for NGINX runtime. 
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Why own interpreter? 


e V8/SpiderMonkey are too heavy to be used inside NGINX. 


e Sophisticated engines, too much overhead not needed in NGINX. 


e Duktape is not fast enough for tasks inside NGINX. 
o Has different sets of priorities. Values memory footprint and ECMAScript 
specs conformance more than performance. 


e Custom interpreter can be tailored to NGINX runtime. 
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e Bytecode compilation at start time. 
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e 00040 ADD 1652F30 1652E10 1652F30 
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Why njs is fast? 
NGINX modules 


* Bytecode compilation at start time. 
o >> 1+1*2 
o 00000 MULTIPLY 1652F30 1652E10 1652F20 
e 00040 ADD 1652F30 1652E10 1652F30 
e 00080 STOP 1652F30 
* Copy-on-write cloning of compiled VM for each request. 
o Fast creation and destroying of VMs. 
* No JIT Compilation 
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Why njs is fast? 
Interpreter 


* Register based VM. 
e Small memory footprint. 

* UTF8 strings, bytes strings optimizations. 
o ECMAScript specs require UTF-16. 


* Disabled garbage collection. 
o Instead cloned VM is destroyed at once. 
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What njs is not 


e nginx + njs is not an application server. 
o not "Node.js" replacement 
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What njs is not 


e nginx + njs is not an application server. 
e not “Node.js” replacement 


e Strict ECMAScript specs conformance (in progress). 
e Huge amount of work to do. Pareto principle. 


45 


Using njs 


Installation 


Installation 
Adding nginx repo (Ubuntu/16.04) 


wget http://nginx.org/keys/nginx signing.key -0 nginx signing.key 
sudo apt-key add nginx signing.key 


echo "deb http://nginx.org/packages/mainline/ubuntu/ xenial nginx" 
-a /etc/apt/sources.list 
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Installation 
Adding nginx repo (Ubuntu/16.04) 


wget http://nginx.org/keys/nginx signing.key -0 nginx signing.key 
sudo apt-key add nginx signing.key 


echo "deb http://nginx.org/packages/mainline/ubuntu/ xenial nginx" 
-a /etc/apt/sources.list 


Installing package 
apt-get update 
sudo apt-get install nginx nginx-module-njs 
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| sudo tee 


Installation 
Adding nginx repo (Ubuntu/16.04) 


wget http://nginx.org/keys/nginx signing.key -0 nginx signing.key 
sudo apt-key add nginx signing.key 


echo “deb http://nginx.org/packages/mainline/ubuntu/ xenial nginx" | sudo tee 
-a /etc/apt/sources.list 


Installing package 
apt-get update 
sudo apt-get install nginx nginx-module-njs 


Examples 
https://github.com/xeioex/njs-examples O 
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Hello world 


nginx.conf: 


load_module 
modules/ngx http js module.so; 
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Hello world 


nginx.conf: 


load_module 
modules/ngx_http_js_module.so; 


http { 
js include example.njs; 
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Hello world 


nginx.conf: 


load_module 
modules/ngx_http_js_module.so; 


http { 
js_include example.njs; 


server { 
listen 8000; 


location /hello { 
js_content hello; 
} 
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Hello world 


nginx.conf: 


load module 
modules/ngx http js module.so; example.njs: 


http 4 function hello(r) 4 
js include example.njs; 
) 


server { 
listen 8000; 


location /hello { 
js content hello; 
) 
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Hello world 


nginx.conf: 


load_module 


modules/ngx_http_js_module.so; example.njs: 
http { function hello(r) { 
js_include example.njs; r.return(200, "Hello world!”); 
) 
server { 


listen 8000; 


location /hello { 
js content hello; 
) 
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Injecting HTTP header 


nginx.conf: 

load_module 
modules/ngx_stream_js_module.so; 
stream { 


js include stream.js; 


server { 
listen 12345; 


proxy pass 127.0.0.1:8000; 
js filter header inject; 
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Injecting HTTP header 


nginx.conf: stream.js: 

var my header = ‘Foo: foo'; 
load module o 
modules/ngx_stream_js_module.so; function header_inject(s) ( 


var reg < ''; 
s.on('upload', function(data, flags) 4 
stream { 
js include stream.js; 


server { 
listen 12345; 


proxy pass 127.0.0.1:8000; 
js filter header inject; 
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Injecting HTTP header 


nginx.conf: stream.js: 
var my header = ‘Foo: foo'; 


load module o 
modules/ngx stream js module.so; function header_inject(s) { 


var reg = ''; 
s.on('upload', function(data, flags) 4 
stream { req += data; 
js_include stream.js; var n = req.search('\n'); 


if (n != -1) 4 


server 4 
listen 12345; 


proxy. pass 127.0.0.1:8000; 
js filter header inject; 
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Injecting HTTP header 


nginx.conf: 


load module 
modules/ngx stream js module.so; 


stream { 
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js include stream.js; 


server { 
listen 12345; 


proxy pass 127.0.0.1:8000; 
js filter header inject; 


stream.js: 
var my header = 


'Foo: foo'; 


function header inject(s) { 


var reg = : 
s.on('upload', function(data, flags) { 
req += data; 
var n = req.search('\n'); 
if (n != -1) { 
var rest = req.substr(n + 1); 
reg = reg.substr(0, n + 1); 


s.send(req + my header + '\r\n' + rest, 


flags); 


ki 
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nginx.conf: 


load_module 
modules/ngx stream js module.so; 


stream { 
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js include stream.js; 


server { 
listen 12345; 


proxy pass 127.0.0.1:8000; 
js filter header inject; 


stream.js: 
var my header = 


'Foo: foo'; 


function header inject(s) { 


var reg = : 
s.on('upload', function(data, flags) { 
req += data; 
var n = req.search('\n'); 
if (n != -1) { 
var rest = req.substr(n + 1); 
reg = reg.substr(0, n + 1); 


s.send(req + my header + '\r\n' + rest, 


flags); 
s.off('upload'); 


ki 
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Joining subrequests 


nginx.conf: 
location /join { 


js content join; 


location /foo { 
proxy pass http://backend1; 


location /bar { 
proxy_pass http://backend2; 


Joining subrequests 


nginx.conf: example.js: 
function join(r) { 


location /join { join subreguests(r, ['/foo', '/bar']); 


js content join; 
) 


location /foo { 
proxy pass http://backend1; 


) 


location /bar { 
proxy_pass http://backend2; 
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Joining subrequests 


nginx.conf: example.js: 
function join(r) { 
location /join { join subreguests(r, ['/foo', '/bar']); 
js content join; } 
} function join_subrequests(r, subs) { 


location /foo { 
proxy_pass http://backend1; 


location /bar { 
proxy_pass http://backend2; 


for (var i in subs) { r.subrequest(subs[i], done);} 


hit 
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Joining subrequests 


nginx.conf: example.js: 
function join(r) { 


location /join { join subreguests(r, ['/foo', '/bar']); 


js content join; } 

} function join_subrequests(r, subs) { 
var parts = []; 

location /foo { 

proxy_pass http://backend1; function done(reply) { 

parts.push({ uri: reply.uri, 
body: reply.responseBody }); 

location /bar { 

proxy_pass http://backend2; 


} 


for (var i in subs) { r.subrequest(subs[i], done);} 


hit 
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Joining subrequests 


nginx.conf: example.js: 


function join(r) { 
location /join { join subreguests(r, ['/foo', '/bar']); 
js content join; } 


} function join_subrequests(r, subs) { 
var parts = []; 
location /foo { 


proxy_pass http://backend1; function done(reply) { 
parts.push({ uri: reply.uri, 
body: reply.responseBody }); 


location /bar { if (parts.length == subs.length) { 
proxy_pass http://backend2; r.return(200, JSON.stringify(parts)); 


) 
) 
for (var i in subs) { r.subreguest(subs[i], done);) 


hit 
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Command line 


docker run -i -t nginx:mainline /usr/bin/njs 


Command line 


docker run -i -t nginx:mainline /usr/bin/njs 
4 [{a:[Date()]}] 


{ 
a: ‘Sun Sep 23 2018 19:15:17 GMT+0000 (UTC) ' 


} 
] 
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Command line 


docker run -i -t nginx:mainline /usr/bin/njs 
H [{a:[Date()]}] 


{ 
a: ‘Sun Sep 23 2018 19:15:17 GMT+0000 (UTC)' 


} 

] 

>> require(‘crypto’).createHash("sha1").update("XX").digest("hex") 
'20026dc165c030fe3a5d9609a6e61ab26210cbc1' 


O 
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Command line 


docker run -i -t nginx:mainline /usr/bin/njs 
i [{a:[Date()]}] 


{ 
a: ‘Sun Sep 23 2018 19:15:17 GMT+0000 (UTC)' 


} 

] 

>> require(‘crypto’).createHash("sha1").update("XX").digest("hex") 
‘20026dc165c030fe3a5d9609a6e61ab26210chc1' 

>> (function(o) {return o.a.a))() 

TypeError: cannot get property 'a' of undefined 

at anonymous (:1) 


at main (native) O 
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Available functionality 


What is available 


* Object, Array, Number, String, Date, 
Regexp, Function 
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What is available 
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e JSON, Math 
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* closures, anonymous functions 


* crypto, files ops and more 
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eval() 
let, const 
arrow functions 


modules 
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Plans 


e More integration with NGINX 
o Embedding njs into NGINX conf files directly. 
o Extending feature set of the modules. 

e njs development 
o Extending ECMAScript specs conformance. 


o Modules support. 


NG VX 


Thank you 


e Github: https://qithub.com/nginx/njs- ia 
e Examples: https://github.com/xeioex/njs-examples 


Dmitry Volyntsev 
xeioex@nginx.com 


Execution model 


example.njs: 
var time = new Date(); 


function variable handler(r) { 
return (Date.now() - time).toString(); 
) 


function content handler(r) { 
r.return(200, “Delay: " + (Date.now() - time)); 
) 
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Decode URI 


nginx.conf: 


http { 
js include example.njs; 


Decode URI 


nginx.conf: 
http { 
js include example.njs; 


js set $dec_foo dec. foo; 
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Decode URI 


nginx.conf: 

http { 
js include example.njs; 
js set $dec_foo dec. foo; 


server { 
listen 8000; 


location /dec foo { 
return 200 $dec_foo; 
) 
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Decode URI 


nginx.conf: 

http { 
js include example.njs; 
js set $dec foo dec foo; 


server { 
listen 8000; 


location /dec foo { 
return 200 Sdec foo; 
) 
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example.njs: 


function dec foo(r) { 
decodeURIComponent(r.args.foo); 
) 


